.TH std::experimental::filesystem::copy_file 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::experimental::filesystem::copy_file \- std::experimental::filesystem::copy_file

.SH Synopsis
   Defined in header <experimental/filesystem>
   bool copy_file( const path& from, const path& to );
   bool copy_file( const path& from, const path& to, error_code& ec \fB(1)\fP (filesystem TS)
   );
   bool copy_file( const path& from, const path& to, copy_options
   options );                                                       \fB(2)\fP (filesystem TS)
   bool copy_file( const path& from, const path& to, copy_options
   options, error_code& ec );

   1) The default, equivalent to \fB(2)\fP with copy_options::none used as options.
   2) Copies a single file from from to to, using the copy options indicated by
   options. The behavior is undefined if there is more than one option in any of the
   copy_options option group present in options (even in the groups not relevant to
   copy_file).
     * If the destination file does not exist,

     * copies the contents and the attributes of the file to which from resolves to the
       file to which to resolves (symlinks are followed).
     * Otherwise, if the destination file already exists:

     * If to and from are the same as determined by equivalent(from, to), report an
       error.
     * Otherwise, if none of the copy_file control options are set in options, report
       an error.
     * Otherwise, if copy_options::skip_existing is set in options, do nothing.
     * Otherwise, if copy_options::overwrite_existing is set in options, copy the
       contents and the attributes of the file to which from resolves to the file to
       which to resolves.
     * Otherwise, if copy_options::update_existing is set in options, only copy the
       file if from is newer than to, as defined by last_write_time().

   The non-throwing overloads return false if an error occurs.

.SH Parameters

   from - path to the source file
   to   - path to the target file
   ec   - out-parameter for error reporting in the non-throwing overload

.SH Return value

   true if the file was copied, false otherwise.

.SH Exceptions

   The overload that does not take an error_code& parameter throws filesystem_error on
   underlying OS API errors, constructed with from as the first argument, to as the
   second argument, and the OS error code as the error code argument. std::bad_alloc
   may be thrown if memory allocation fails. The overload taking an error_code&
   parameter sets it to the OS API error code if an OS API call fails, and executes
   ec.clear() if no errors occur. This overload has
   noexcept specification:
   noexcept


.SH Notes

   The functions involve at most one direct or indirect call to status(to) (used both
   to determine if the file exists, and, for copy_options::update_existing option, its
   last write time).

   Error is reported when copy_file is used to copy a directory: use copy for that.

   copy_file follows symlinks: use copy_symlink or copy with
   copy_options::copy_symlinks for that.

.SH Example


// Run this code

 #include <experimental/filesystem>
 #include <fstream>
 #include <iostream>
 namespace fs = std::experimental::filesystem;

 int main()
 {
     fs::create_directory("sandbox");
     std::ofstream("sandbox/file1.txt").put('a');

     fs::copy_file("sandbox/file1.txt", "sandbox/file2.txt");

     // now there are two files in sandbox:
     std::cout << "file1.txt holds : "
               << std::ifstream("sandbox/file1.txt").rdbuf() << '\\n';
     std::cout << "file2.txt holds : "
               << std::ifstream("sandbox/file2.txt").rdbuf() << '\\n';

     // fail to copy directory
     fs::create_directory("sandbox/abc");
     try
     {
         fs::copy_file("sandbox/abc", "sandbox/def");
     }
     catch (fs::filesystem_error& e)
     {
         std::cout << "Could not copy sandbox/abc: " << e.what() << '\\n';
     }
     fs::remove_all("sandbox");
 }

.SH Possible output:

 file1.txt holds : a
 file2.txt holds : a
 Could not copy sandbox/abc: copy_file: Is a directory: "sandbox/abc", "sandbox/def"

.SH See also

   copy_options specifies semantics of copy operations
                \fI(enum)\fP
   copy_symlink copies a symbolic link
                \fI(function)\fP
   copy         copies files or directories
                \fI(function)\fP

.SH Categories:
     * Noindexed pages
     * unconditionally noexcept
.SH Hidden categories:
     * Pages with unreviewed unconditional noexcept template
     * Pages with unreviewed noexcept template
